To make life easier for programmers, the Amiga already contains numerous special routines for you to use. These functions are placed in different "libraries" depending on their general type. Some of these routines will open and close other libraries, draw graphics, menus and requesters, move sprites, etc. And there are even ways to create your own libraries for your specialized functions. Libraries are usually located in memory or on your boot disk. The major libraries we'll use are:
TRANSLATOR - convert word strings to phonetic strings
MATH - there are several math libraries for single or double
precision and regular or special functions (trigonometric,
logs powers, roots, etc.)
When you first turn on the Amiga the locations of these libraries may be different from previous times so you can't directly use one of the routines, but must open the library first. There is one constant, however, the address of the EXEC library is always at location $4; since addresses in the Amiga are usually long they are given as HEX values omitting the #. Within the EXEC library are routines to open and close any other library. The reference to any library routine is always a negative number used as an offset from a library location. This offset is not the start of the routine but, rather, the location of the address for that routine (if the format JSR ########). For example, the address for the routine to open a library is located at -552, or 552 bytes away from the EXEC library beginning; the address of the routine to close a library is at -414. You don't need to worry about the actual address, but you do need to know where they're located - those negative offsets. A little later I'll show you how the assembler will help you with this.
In almost every library routine certain registers must contain specific information and the result, if any, is returned in specific registers, usually D0. To open a library the location of the EXEC library address ($4) is put in A6, the latest library version desired or, more usually, a 0 for "don't care what version" in D0 and the library name address in A0; the desired library location will be returned in D0. The library name is a name location in your program that contains the actual library name. You'll see how the assembler does this shortly. Most of these library names except for the math ones are the name of the library itself followed by ".library".
OPEN/CLOSE A LIBRARY
Let's see how to open the INTUITION library. The library name will be at a location called INT and we'll store the returned address in a location called INTBASE. A short routine to open this library could be -
MOVEA.L $4,A6 ;contains the EXEC library address
LEA INT,A0 ;location of INTUITION library name
MOVEQ #0,D0 ;use any version #
JSR -552,(A6) ;jump to the routine -552 bytes from the
;address in A6 and return when finished
MOVE.L D0,INTBASE ;save the address, set flags
BEQ ERROR ;branch if not located
Most routines follow this format. I could have used TST on D0 to see if there was an address, but MOVEing will set the ZERO flag anyway, so check afterwards. To close the library, which you must do when you're finished with it or at the end of the program, the library address must be in A1. Use code like -
MOVEA.L $4,A6 ;contains the EXEC library address
MOVEA.L INTBASE,A1 ;address of intuition library
JSR -414(A6) ;jump to the close library routine and return
The routines for opening and closing libraries are the same for all libraries so they are perfect candidates for MACROS - routines that are always performed in the same manner with only the names or values changed. More on macros in a later article.
ORGANIZING A PROGRAM
Now it's time to look at the PHXASS assembler and see how we can begin to write a program. The first line needs to let the assembler know that this section is code to be assembled so use (tab) SECTION (tab) TEXT,CODE. Next would probably be any files you want included that are referred to within the program. These files might contain the offset values for certain libraries, macro routines, etc. Add these files using (tab) INCLUDE (tab) FILENAME; you may have several include files.
This would be followed by your "equates". These are values to be used in place of words you use in your code. In the program we just listed above you might use -
;EXEC OFFSETS
OPENLIBRARY = -552
CLOSELIBRARY = -414
Now you could use code like - JSR OPENLIBRARY(A6). While you may assign any name to a value, there are certain names usually used by all programmers to make their source code work for anyone. I'll always try to use these standard equates. In the same manner you can equate names to the various registers with EQUR. Using ACROSS EQUR D6 and DOWN EQUR D5 would always store whatever value you put in those labels into either of the two registers; you can also use those registers anywhere else. You may have variables in your program that you want to change and test for new values. You could use LEN = 32, assemble and try the program, then change LEN = 64, reassemble and retry the program. Anywhere there is LEN in your code will now be replaced with #64.
This section is usually followed by any macros or routines specific to the program. Then there is the program itself. After the program all the data is listed. This usually starts with the code EVEN to be sure it begins on a long word address. Space for any variables to be computed is reserved using NAME DC.B/.W/.L depending if it's a byte, word, or long word, followed by the initial value, usually 0. For example, the address of the DOS library, when opened, gets stored in DOSBASE so reserve space for this long word value using DOSBASE DC.L 0. Separate any non long word values with EVEN to keep them aligned.
Another use for DC.B is to store string phrases or numbers. These must be in quotes and are usually followed by a 0 to indicate the end of the string. This is how those library names get entered. You might store the INTUITION library name using INT DC.B 'INTUITION.LIBRARY',0. Now the location INT can be used as the address of the library name to go in A0. Multiple values of the same length can go on the same line such as -
COLORTABLE DC.W $0C64,$0D43,$0E22,$OFO1
Word equivalents may be used in any storage location or code as long as they have been equated to a numerical value in your listing or in an include file. Storage space for lots of data can be reserved using DCB or BLK.B/.W/.L HOW_MANY,FILL_VALUE or DS.B/.W/.L HOW_MANY; the latter will automatically fill the block with zeroes. If you haven't done so already, now is a good time to read the PHXASS.DOC manual.
Let's write a program that will open the DOS library and print it's location, in HEX, to the screen. A new command first - ROL/R. This command will rotate a register left or right one bit; the bit that goes off the end rotates back to the other end, so it takes 32 rotations to restore a register to it's original contents. This command will help us isolate each four-bit number and convert it to a CHR$. We'll use the DOS function WRITE which writes the contents of a buffer to the screen. WRITE needs the location of an output file in D1, the input buffer or string location in D2 and the length of the text in D3. The DOS routine OUTPUT will return the output file address in D0 which is usually stored in memory location CONHANDLE. When using WRITE the text or buffer contents do not need to be null (0) terminated since the number of bytes to print is in D3; it's still a good idea to terminate strings with 0, however, since most other routines require it.
USING LISTING 1
With this information, let's follow Listing 1. There are four offset equates for the routines the program uses. After saving the stack pointer the DOS library is opened and it's address used in OUTPUT to get CONHANDLE. The DOS library address is put in D0 and our input BUFFER address in A0. Rotating D0 four bits to the left moves the left-most number to the right end since we'll be storing this number as a character in the buffer first; move this value into D2 so we can modify it. AND the register with #$F to be sure that D2 contains only a number from 0 to #$F; since the CHR$ for letters starts at #$30 add this to D2. If the current character value is for a 0 to 9 branch to OK; if not, add 7 to convert it to the CHR$ value for A to F. Putting the character we're using in quotes instead of it's actual character value is much easier that trying to remember all those character values. Move this value to the buffer location and increase the buffer address by 1; the "+" after (A0) means to increase that register by the size of the MOVE command. Add 1 to D3 and see if we've filled our buffer with 8 characters yet; if not, repeat the process.
When the buffer is full (eight characters), put the CONHANDLER address if D1 and the BUFFER address in D2; increase the length in D3 by 1 since we'll also print a line feed (CHR$10) after the eight numbers. Then call the WRITE function, close the DOS library and restore the stack. Type and save Listing 1 as DEMODOS.ASM; assemble it with PHXASS DEMODOS.ASM and link it using PHXLNK DEMODOS.O. Run the program DEMODOS and you'll see the location of your DOS library. This routine could be modified to print the HEX contents of any register; could you print the decimal value instead? Or, how about first printing a message giving the library name followed by it's location; try this for several libraries.
For a more in-depth discussion of these first articles refer to AC's TECH magazine V2.1 (pages 45-52). Next time we'll do some math and write a program for a financial calculator. Until then, happy programming. ú─Çr└╥ê c¼u═┬P╗A╕!ä¼
